I hope the noob (me) did this correctly...
Addresses bug #759 https://github.com/coleam00/Archon/issues/759

• Introduced ScrollableDialogContent component for better user experience in AddKnowledgeDialog.
• Updated dialog structure to include a fixed header and scrollable body, improving accessibility and usability.
• Adjusted styles to maintain visual consistency and added maxHeight prop for dynamic height management.
• Updated .gitignore to include DIALOG-FIX.md for better tracking of dialog-related changes.

This change enhances the Add Knowledge dialog's functionality, making it more user-friendly while adhering to design principles.

Pull Request

Summary

Dialog Overflow Fix Proposal

Problem Analysis

The AddKnowledgeDialog currently exceeds window boundaries and gets cut off on smaller screens or when the dialog content is too tall. The issue stems from:

1. Fixed positioning: Dialog uses fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 which centers it but doesn't respect viewport boundaries
2. No height constraints: Dialog content can grow indefinitely without scroll handling
3. Missing responsive behavior: No fallback for smaller screens or overflow scenarios

Root Cause

Current DialogContent implementation (lines 42-62 in dialog.tsx):

className={cn(
  "fixed left-1/2 top-1/2 z-50 -translate-x-1/2 -translate-y-1/2",
  "p-6 rounded-md backdrop-blur-md",
  "w-full max-w-2xl", // Only width constraint, no height constraint
  // ... styling classes
)}

AddKnowledgeDialog usage (line 130):

<DialogContent className="sm:max-w-[600px]"> // Still no height constraint

Proposed Solution

1. Enhanced DialogContent Component

Modify DialogContent to include responsive height constraints and scroll behavior:

// In dialog.tsx - Enhanced DialogContent
export const DialogContent = React.forwardRef<
  React.ElementRef<typeof DialogPrimitive.Content>,
  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content> & {
    showCloseButton?: boolean;
    maxHeight?: string; // New prop for custom height constraints
  }
>(({ className, children, showCloseButton = true, maxHeight = "90vh", ...props }, ref) => (
  <DialogPortal>
    <DialogOverlay />
    <DialogPrimitive.Content
      ref={ref}
      className={cn(
        "fixed left-1/2 top-1/2 z-50 -translate-x-1/2 -translate-y-1/2",
        "p-6 rounded-md backdrop-blur-md",
        "w-full max-w-2xl",
        // NEW: Height constraints and scroll behavior
        `max-h-[${maxHeight}]`, // Configurable max height
        "overflow-hidden", // Prevent content from breaking out
        // ... existing styling classes
        className,
      )}
      style={{ maxHeight }} // Ensure maxHeight prop works
      {...props}
    >
      <div className="relative z-10 h-full flex flex-col">
        {children}
      </div>
      {showCloseButton && (
        <DialogPrimitive.Close
          className={cn(
            "absolute right-4 top-4 z-20",
            "text-gray-500 dark:text-gray-400",
            "hover:text-gray-700 dark:hover:text-white",
            "transition-colors",
          )}
        >
          <X className="h-5 w-5" />
          <span className="sr-only">Close</span>
        </DialogPrimitive.Close>
      )}
    </DialogPrimitive.Content>
  </DialogPortal>
));

2. New ScrollableDialogContent Component

Create a specialized component for dialogs that need scrollable content:

// In dialog.tsx - New ScrollableDialogContent
export const ScrollableDialogContent = React.forwardRef<
  React.ElementRef<typeof DialogPrimitive.Content>,
  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content> & {
    showCloseButton?: boolean;
    maxHeight?: string;
  }
>(({ className, children, showCloseButton = true, maxHeight = "90vh", ...props }, ref) => (
  <DialogPortal>
    <DialogOverlay />
    <DialogPrimitive.Content
      ref={ref}
      className={cn(
        "fixed left-1/2 top-1/2 z-50 -translate-x-1/2 -translate-y-1/2",
        "rounded-md backdrop-blur-md",
        "w-full max-w-2xl",
        `max-h-[${maxHeight}]`,
        "overflow-hidden flex flex-col",
        // ... existing styling classes
        className,
      )}
      style={{ maxHeight }}
      {...props}
    >
      {/* Fixed Header */}
      <div className="flex-shrink-0 p-6 pb-4">
        {children}
      </div>
      
      {/* Scrollable Body */}
      <div className="flex-1 overflow-y-auto px-6 pb-6">
        {/* Content goes here - this will be scrollable */}
      </div>
      
      {showCloseButton && (
        <DialogPrimitive.Close
          className={cn(
            "absolute right-4 top-4 z-20",
            "text-gray-500 dark:text-gray-400",
            "hover:text-gray-700 dark:hover:text-white",
            "transition-colors",
          )}
        >
          <X className="h-5 w-5" />
          <span className="sr-only">Close</span>
        </DialogPrimitive.Close>
      )}
    </DialogPrimitive.Content>
  </DialogPortal>
));

3. Enhanced AddKnowledgeDialog Implementation

Modify AddKnowledgeDialog to use the new scrollable component:

// In AddKnowledgeDialog.tsx
return (
  <Dialog open={open} onOpenChange={onOpenChange}>
    <ScrollableDialogContent className="sm:max-w-[600px]" maxHeight="85vh">
      {/* Fixed Header */}
      <DialogHeader>
        <DialogTitle>Add Knowledge</DialogTitle>
        <DialogDescription>Crawl websites or upload documents to expand your knowledge base.</DialogDescription>
      </DialogHeader>

      {/* Scrollable Content */}
      <div className="overflow-y-auto">
        <Tabs value={activeTab} onValueChange={(v) => setActiveTab(v as "crawl" | "upload")}>
          {/* Enhanced Tab Buttons */}
          <div className="grid grid-cols-2 gap-3 p-2 rounded-xl backdrop-blur-md bg-gradient-to-b from-gray-100/30 via-gray-50/20 to-white/40 dark:from-gray-900/30 dark:via-gray-800/20 dark:to-black/40 border border-gray-200/40 dark:border-gray-700/40">
            {/* ... existing tab buttons */}
          </div>

          {/* Crawl Tab */}
          <TabsContent value="crawl" className="space-y-6 mt-6">
            {/* ... existing crawl content */}
          </TabsContent>

          {/* Upload Tab */}
          <TabsContent value="upload" className="space-y-6 mt-6">
            {/* ... existing upload content */}
          </TabsContent>
        </Tabs>
      </div>
    </ScrollableDialogContent>
  </Dialog>
);

4. Alternative: CSS-Only Solution

If you prefer a simpler approach, modify only the existing DialogContent:

// In dialog.tsx - Simple CSS-only fix
export const DialogContent = React.forwardRef<
  React.ElementRef<typeof DialogPrimitive.Content>,
  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content> & {
    showCloseButton?: boolean;
  }
>(({ className, children, showCloseButton = true, ...props }, ref) => (
  <DialogPortal>
    <DialogOverlay />
    <DialogPrimitive.Content
      ref={ref}
      className={cn(
        "fixed left-1/2 top-1/2 z-50 -translate-x-1/2 -translate-y-1/2",
        "p-6 rounded-md backdrop-blur-md",
        "w-full max-w-2xl",
        // NEW: Height constraints and scroll
        "max-h-[90vh]", // Constrain to 90% of viewport height
        "overflow-y-auto", // Enable vertical scrolling
        // ... existing styling classes
        className,
      )}
      {...props}
    >
      <div className="relative z-10">{children}</div>
      {/* ... existing close button */}
    </DialogPrimitive.Content>
  </DialogPortal>
));

Implementation Steps

Option A: Enhanced Components (Recommended AND IMPLEMENTED)

1. Update dialog.tsx:

   • Add ScrollableDialogContent component
   • Enhance DialogContent with optional height constraints
   • Maintain backward compatibility

2. Update AddKnowledgeDialog.tsx:

   • Replace DialogContent with ScrollableDialogContent
   • Restructure content into fixed header and scrollable body
   • Test on various screen sizes

3. Test & Validate:

   • Test on mobile devices (320px width)
   • Test with long content (many tags, long URLs)
   • Verify scroll behavior is smooth
   • Ensure close button remains accessible

Option B: CSS-Only Fix (Quick Solution)

1. Update dialog.tsx:

   • Add max-h-[90vh] and overflow-y-auto to DialogContent
   • No structural changes needed

2. Test:

   • Verify scroll behavior
   • Check mobile responsiveness

Benefits

• Responsive: Works on all screen sizes
• Accessible: Maintains keyboard navigation and focus management
• Consistent: Preserves existing design aesthetics
• Flexible: Configurable height constraints
• Performance: Minimal impact on existing functionality

Considerations

• Close button: Ensure it remains visible and accessible
• Scroll indicators: Consider adding subtle scroll indicators
• Mobile optimization: May need additional mobile-specific adjustments
• Backward compatibility: Existing dialogs should continue working

Testing Checklist

Manual Tests:

• Dialog fits within viewport on 320px width screens
• Scroll behavior is smooth and intuitive
• Close button remains accessible when scrolled
• Tab navigation works correctly when scrolled
• Form validation and submission work correctly
• Keyboard navigation (Tab, Enter, Escape) works properly
• Screen reader accessibility is maintained
• Visual design remains consistent

Recommended Approach

Use Option A (Enhanced Components) for the following reasons:

1. Better UX: Fixed header keeps title/description visible
2. Maintainable: Clear separation of concerns
3. Reusable: Can be used for other large dialogs
4. Future-proof: Easier to extend with additional features

The enhanced approach provides better user experience while maintaining the existing design system and ensuring accessibility standards are met.

Changes Made

1. Update dialog.tsx:

   • Add ScrollableDialogContent component
   • Enhance DialogContent with optional height constraints
   • Maintain backward compatibility

2. Update AddKnowledgeDialog.tsx:

   • Replace DialogContent with ScrollableDialogContent
   • Restructure content into fixed header and scrollable body
   • Test on various screen sizes

3. Test & Validate:

   • Test on mobile devices (320px width)
   • Test with long content (many tags, long URLs)
   • Verify scroll behavior is smooth
   • Ensure close button remains accessible

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Performance improvement
• Code refactoring

Affected Services

• Frontend (React UI)
• Server (FastAPI backend)
• MCP Server (Model Context Protocol)
• Agents (PydanticAI service)
• Database (migrations/schema)
• Docker/Infrastructure
• Documentation site

Testing

• All existing tests pass
• Added new tests for new functionality
• Manually tested affected user flows
• Docker builds succeed for all services

Test Evidence

Checklist

• My code follows the service architecture patterns
• If using an AI coding assistant, I used the CLAUDE.md rules
• I have added tests that prove my fix/feature works
• All new and existing tests pass locally
• My changes generate no new warnings
• I have updated relevant documentation
• I have verified no regressions in existing features

Breaking Changes

Additional Notes

Summary by CodeRabbit

• New Features

  • Introduced a scrollable dialog option with configurable maximum height and optional close button for improved usability on smaller screens.

• Refactor

  • Updated the Add Knowledge dialog to use a fixed header and a scrollable content area, improving readability and navigation without altering existing crawl or upload functionality.
  • Adjusted tab layout and helper text styling to align with the new scrollable structure.

• Chores

  • Updated ignored files to exclude DIALOG-FIX.md.